.\" Process this file with
.\" nroff -e -mandoc foo.1
.\"
.TH netconfd 1 "February 6, 2012" Linux "netconfd 2.2"
.SH NAME
netconfd \- YANG-based NETCONF-over-SSH server

.SH SYNOPSIS
.nf

   netconfd [parameter=value...]

   netconfd --help [brief | normal | full]

   netconfd --version

.fi
.SH DESCRIPTION
.B netconfd
is a YANG-based NETCONF server, which can be used with
an SSH server such as OpenSSH.
This version of netconfd supports the YANG data modeling language
defined in \fBdraft-ietf-netmod-yang-12.txt\fP.
.SH USAGE
Parameters can be entered in any order, and have the form:

   \fB[start] name [separator [value]]\fP

where:

    \fBstart\fP == 0, 1, or 2 dashes (foo, -foo, --foo)

    \fBname\fP == parameter name
.nf

         Parameter name completion will be attempted 
         if a partial name is entered.

.fi
    \fBseparator\fP == whitespace or equals sign (foo=bar, foo bar)

    \fBvalue\fP == string value for the parameter.
.nf

         Strings with whitespace need to be double quoted 
         (--foo="some string")

.fi
Some examples of valid command line parameters:
.nf

   foo=3
   -foo=3
   --foo=3
   foo 3
   foo=fred
   --foo "fred flintstone"
.fi

Partial parameter names can be entered if they are unique.

.SH OPTIONS
.IP --\fBaccess-control\fP=enum
Controls how the yuma-nacm access control model will
be enforced during server operation.
.nf
 Enum values:
    enforcing:
      All configured access control rules will be
      enforced.
    permissive:
      All configured access control rules will be
      enforced for write and execute requests.
      All read requests will be allowed, unless
      the requested object contains the
      'nacm:very-secure' extension.  In that case,
      all configured access control rules will
      be enforced.
   disabled:
      All read, write, and execute requests will be
      allowed, unless the object contains the
      'nacm:secure' or 'nacm:very-secure' extension.
      If the 'nacm:secure' extension is in effect,
      then all configured access control rules
      will be enforced for write and execute requests.
      If the 'nacm:very-secure' extension is in effect,
      then all configured access control rules
      will be enforced for all requests.
      Use this mode with caution.
   off:
      All access control enforcement is disabled.
      Use this mode with extreme caution.
.fi
.IP --\fBaudit-log\fP=filespec
Filespec for the server audit log file to use in addition
to the normal log file or STDOUT.
.IP --\fBaudit-log-append\fP
If present, the audit log will be appended not over-written.
If not, the audit log will be over-written.
Only meaningful if the 'audit-log' parameter is also present.
.IP --\fBconfig\fP=filespec
The name of the configuration file to use.
Any parameter except this one can be set in the config file.
The default config file 
.I /etc/yuma/netconfd.conf
will be not be checked if this parameter is present.
.IP --\fBdatapath\fP=list
Internal file search path for configuration data files.
Overrides the YUMA_DATAPATH environment variable.
This parameter affects the search for the startup 
configuration file (default: startup-cfg.xml).
.IP --\fBdefault-style\fP=enum 
Selects the type of filtering behavior the server will
advertise as the 'basic' behavior in the 'with-defaults'
capability.  The server will use this default handling
behavior if the 'with-defaults' parameter is not 
explicitly set.

Also, when saving a configuration to NV-storage,
this value will be used for filtering defaults
from the saved configuration.
.nf
  Enum values:
     report-all: report all values
     trim: remove leafs containing the YANG
        default value
     explicit: report only the nodes that have
        been created by the client or the server.
        This is the default value.
.fi
.IP --\fBdelete-empty-npcontainers\fP=boolean
Selects whether the server will keep or delete empty
non-presence containers in the running and startup 
configurations. Set to true to delete these containers,
and false to keep them.  Default: false.
This parameter is deprecated!  It is ignored by the server!
.IP --\fBdeviation\fP=string
 This parameter identifies a YANG module that
should only be checked for deviation statements
for external modules.  These will be collected
and applied to the real module(s) being processed.
       
Deviations are applied as patches to the target module.
Since they are not identified in the target module at
all (ala imports), they have to be specified
explicitly, so they will be correctly processed.
Zero or more instances of this parameter are allowed.
.IP --\fBeventlog-size\fP=number
Specifies the maximum number of notification events
that will be saved in the notification replay buffer.
The oldest entries will be deleted first.
The default value is  1000.
.IP --\fBfeature-disable\fP=module:feature
Identifies a feature which should be considered disabled.
Zero or more entries are allowed.
.IP --\fBfeature-enable-default\fP=boolean
If true (the default), then features will be enabled by default.
If false, then features will be disabled by default.
.IP --\fBfeature-enable\fP=module:feature
Identifies a feature which should be considered enabled.
Zero or more entries are allowed.
.IP --\fBhello-timeout\fP=number
Specifies the number of seconds that a session
may exist before the hello PDU is received.
A seesion will be dropped if no hello PDU 
is received before this number of seconds elapses.

If this parameter is set to zero, then the server
will wait forever for a hello message, and not
drop any sessions stuck in 'hello-wait' state.

Setting this parameter to zero may permit
denial of service attacks, since only a limited
number of concurrent sessions are supported
by the server. (range 0 | 10 .. 3600).
The default value is 600 seconds (10 minutes).
.IP --\fBhelp\fP
Print this help text and exit.
The help-mode choice (--brief, --normal, or --full) may also be present
to control the amount of help text printed.
.IP --\fBhome\fP=dirspec
Directory specification for the home directory
to use instead of HOME.
.IP --\fBidle-timeout\fP=number
Specifies the number of seconds that a session
may remain idle without issuing any RPC requests.
A seesion will be dropped if it is idle for an
interval longer than this number of seconds.

Sessions that have a notification subscription
active are never dropped. 

If this parameter is set to zero, then the server
will never drop a session because it is idle.
(range 0 | 10 .. 360000).  The default value is
3600 seconds (1 hour).
.IP --\fBindent\fP=number
Number of spaces to indent (0..9) in formatted output.
The default is 2 spaces.
.IP --\fBlog\fP=filespec
Filespec for the log file to use instead of STDOUT.
If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character.  If it begins
with a '$' character, then an environment variable
name is expected to follow.
.IP --\fBlog-append\fP
If present, the log will be appended not over-written.
If not, the log will be over-written.
Only meaningful if the \fBlog\fP parameter is
also present.
.IP --\fBlog-level\fP=enum
Sets the debug logging level for the program.
.IP --\fBmax-burst\fP=number
Specifies the maximum number of notifications
that should be sent to one session, within a
one second time interval.  The value 0 indicates 
that the server should not limit notification
bursts at all.  The default value is 10.
.IP --\fBmodpath\fP=list
Directory search path for YANG and YIN files.
Overrides the YUMA_MODPATH environment variable.
.IP --\fBmodule\fP=string
YANG or YIN source module name to load at startup.
The server will attempt to load the specified
module and its corresponding server instrumentation
library (SIL) .

If this string represents a filespec, 
ending with the \fB.yang\fP or \fB.yin\fP extension,
then only that file location will be checked.

If this string represents a module name, then
the module search path will be checked for
a file the \fB.yang\fP or \fB.yin\fP extension.

If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character.  If it begins
with a '$' character, then an environment variable
name is expected to follow.
.nf

      ~/some/path ==> <my-home-dir>/some/path

      ~fred/some/path ==> <fred-home-dir>/some/path

      $workdir/some/path ==> <workdir-env-var>/some/path
.fi
.IP --\fBport\fP=number
Specifies the TCP ports that the server will accept
connections from.  These ports must also be configured
in the /etc/ssh/sshd_config file for the SSH master
server to accept the connection and invoke the netconf
subsystem.

Up to 4 port numbers can be configured.

If any ports are configured, then only those values
will be accepted by the server.

If no ports are configured, then the server will accept
connections on the netconf-ssh port (tcp/830).
.IP --\fBprotocols\fP=bits
Specifies which NETCONF protocol versions the server
will attempt to use. The empty set is not allowed.
The values 'netconf1.0' and 'netconf1.1' are supported.
The default is to enable both NETCONF protocol versions.
.IP --\fBrunpath\fP=pathlist
Internal file search path for executable modules.
Overrides the YUMA_RUNPATH environment variable.
.IP --\fBrunning-error\fP=enum
If 'stop', then errors in the running configuration will be
treated as fatal errors.  If 'continue', the server will attempt
to continue if any validataion errors are found in the
running configuration at startup.  The default is 'stop'.
.IP --\fBstartup\fP=filespec
The full or relative filespec of the startup config file to use.
If present, overrides the default startup config
file name 'startup-cfg.xml',  This will also
override the YUMA_DATAPATH environement variable
and the datapath CLI parameter, if the first
character is the forward slash '/', indicating
an absolute file path.  If this parameter is present,
then the --no-startup and --factory-startup parameters cannot be present.
This is the default, which will cause startup-cfg.xml to
be used if not present.
.IP --\fBno-startup\fP
If present, do not load the startup config file.
Use only factory default values instead.
Does not affect the startup.cfg file, if present.
If this parameter is present, then the --startup
or --factory-startup parameter cannot be present.
.IP --\fBfactory-startup\fP
Force the system to use the factory configuration
and delete the startup config file if it exists.
Force the NV-storage startup to
contain the factory default configuration.
If this parameter is present,
then the --no-startup and --startup parameters cannot be present.
.IP --\fBstartup-error\fP=enum
If 'stop', then any errors in the startup configuration will be
treated as fatal errors.  If 'continue', the server will attempt
to continue if any errors are found in the database loaded 
from NV-storage to running at boot-time.
.IP --\fBsubdirs\fP=boolean
If false, the file search paths for modules, scripts, and data
files will not include sub-directories if they exist in the
specified path.
      
If true, then these file search paths will include
sub-directories, if present.  Any directory name beginning
with a dot (\fB.\fP) character, or named \fBCVS\fP, will be ignored.
This is the default mode.
.IP --\fBsuperuser\fP=string
The user name to use as the superuser account.
Any session associated with this user name 
will bypass all access control enforcement.
See yuma-nacm.yang for more details.
There is no default value.
.IP --\fBsystem-sorted\fP=boolean
Indicates whether ordered-by system leaf-lists 
and lists will be kept in sorted order.
The default is true.
.IP --\fBtarget\fP=enum
Specifies the database to use as the target of edit-config
operations.
.nf
  Enum values:
    running:
      Write to the running config and support the
      :writable-running capability.
    candidate:
      Write to the candidate config and support the
      :candidate and :confirmed-commit capabilities.
.fi
.IP --\fBusexmlorder\fP
If present, then XML element order will be enforced.
Otherwise, XML element order errors will not be
generated if possible. Default is no enforcement of
strict XML order.
.IP --\fBversion\fP
Print the program version string and exit.
.IP --\fBwarn-idlen\fP=number
 Control whether identifier length warnings will be
generated.  The value zero disables all identifier
length checking.  If non-zero, then a warning will
be generated if an identifier is defined which 
has a length is greater than this amount.
range: 0 | 8 .. 1023.
The default value is 64.
.IP --\fBwarn-linelen\fP=number
Control whether line length warnings will be
generated.  The value zero disables all line length
checking.  If non-zero, then a warning will
be generated if the line length is greater than
this amount.  Tab characters are counted as 8 spaces.
range: 0 | 40 .. 4095.
The default value is 72.
.IP --\fBwarn-off\fP=number
Control whether the specified warning number will be
generated and counted in the warning total for the
module being parsed.
range: 400 .. 899.
This parameter may be entered zero or more times.
.IP --\fBwith-startup\fP=boolean
If set to 'true', then the :startup capability will be 
enabled. Otherwise, the :startup capability
will not be enabled.  This capability 
makes the NV-save operation an explicit operation
instead of an automatic save.  The default value is false.
.IP --\fBwith-url\fP=boolean
If set to 'false', then the :url capability will be 
disabled. Otherwise, the :url capability
will be enabled.  This capability 
allows local files to be stored as backups on the server.
The default value is true.
.IP --\fBwith-validate\fP=boolean
If set to 'true', then the :validate capability will be 
enabled. Otherwise, the :validate capability
will not be enabled.  This capability requires
extensive memory resources.  The default value is true.
.IP --\fByuma-home\fP=string
Directory for the yuma project root to use.
If present, this directory location will
override the YUMA_HOME environment variable,
if it is present.  If a zero-length string is
entered, then the YUMA_HOME environment variable
will be ignored.
.SH INPUT FILES
YANG modules can be loaded at startup with the '--module' command,
or loaded at run-time with the 'load' operation.
.SH SEARCH PATH
When a module name is entered as input, or when a
module or submodule name is specified in an import or include
statement within the file, the following search algorithm
is used to find the file:
.nf    

  1) file is in the current directory
  2) YUMA_MODPATH environment var (or set by modpath parameter)
  3) $HOME/modules directory
  4) $YUMA_HOME/modules directory
  5) $YUMA_INSTALL/modules directory OR
     default install module location, '/usr/share/yuma/modules'

.fi
By default, the entire directory tree for all locations
(except step 1) will be searched, not just the specified
directory.  The \fBsubdirs\fP parameter can be used to
prevent sub-directories from being searched.
    
Any directory name beginning with a dot character (\fB.\fP)
will be skipped.  Also, any directory named \fBCVS\fP will
be skipped in directory searches.

.SH ERROR LOGGING
By default, warnings and errors are sent to STDOUT.
    
A log file can be specified instead with the \fBlog\fP' parameter.

Existing log files can be reused with the 'logappend'
parameter, otherwise log files are overwritten.
    
The logging level can be controlled with the \fBlog-level\fP
parameter.

The default log level is 'info'.  The
log-levels are additive:
.nf

     off:    suppress all errors (not recommended!)
             A program return code of '1' indicates some error.
     error:  print errors
     warn:   print warnings
     info:   print generally interesting trace info
     debug:  print general debugging trace info
     debug2: print verbose debugging trace info
     debug3: print very verbose debugging trace info
     debug4: print maximum debugging trace info

.fi

.SH ENVIRONMENT
The following optional environment variables can be used
to control module search behavior:

.IP \fBHOME\fP
The user's home directory  (e.g., /home/andy)
.IP \fBYUMA_HOME\fP
The root of the user's Yuma work directory
(e.g., /home/andy/swdev/netconf)
.IP \fBYUMA_INSTALL\fP
The root of the directory that yangdump
is installed on this system (default is, /usr/share/yuma)
.IP \fBYUMA_DATAPATH\fP
Colon-separated list of directories to
search for data files.
(e.g.: './workdir/data-files:/home/andy/data')
The \fBdatapath\fP parameter will override this
environment variable, if both are present.
.IP \fBYUMA_MODPATH\fP
Colon-separated list of directories to
search for modules and submodules.
(e.g.: './workdir/modules:/home/andy/test-modules')
The \fBmodpath\fP parameter will override this
environment variable, if both are present.

.SH CONFIGURATION FILES
.IP \fByangdump.conf\fP
YANG config file
The default is: \fB/etc/yuma/yangdump.conf\fP
    
An ASCII configuration file format is supported to
store command line parameters. 

The \fBconfig\fP parameter
is used to specify a specific config file, otherwise
the default config file will be checked.
.nf    

   - A hash mark until EOLN is treated as a comment
   - All text is case-sensitive
   - Whitespace within a line is not significant
   - Whitespace to end a line is significant/
     Unless the line starts a multi-line string,
     an escaped EOLN (backslash EOLN) is needed
     to enter a leaf on multiple lines.
   - For parameters that define lists, the key components
     are listed just after the parameter name, without
     any name,  e.g.,
    
            interface eth0 {
              # name = eth0 is not listed inside the braces
              ifMtu 1500
              ifName mySystem
            }

.fi    
A config file can contain any number of parameter
sets for different programs. 

Each program must have its own section, identifies by its name:
.nf    

     # this is a comment
     yangdump {
        log-level debug
        output "~/swdev/testfiles"
     }
    
     netconfd {
        ...
     }

.fi

.SH FILES
The following data files must be present in the module
search path in order for this program to function:
    
  * \fBYANG module library\fP
    default: /usr/share/yuma/modules/
    

.SH DIAGNOSTICS
Internal diagnostics may generate the following
type of message if any bugs are detected at runtime:
.nf  

    [E0]
         filename.c:linenum error-number (error-msg)

.fi
.SH AUTHOR
Andy Bierman, <andy at netconfcentral dot org>

.SH SEE ALSO
.BR netconf-subsystem (1)
.BR pyang (1)
.BR smidump (1)
.BR yangcli (1)
.BR yangdiff (1)
.BR yangdump (1)

